Panel VAR Modeling
==================

A ``prfvar`` object models a **panel** of (possibly Markov-switching)
reduced-form VARs: the same set of variables observed for several
cross-sectional units (countries, sectors, ...), stacked into one system whose
coefficients are linked across units according to a chosen *homogeneity*
assumption. It extends the ``rfvar`` object, so data handling, estimation,
identification, forecasting and the various decompositions are exactly as in
:doc:`../ReducedFormVAR_capabilities/Main Reduced form VAR Modeling`; this page
covers what is specific to the panel case.

The model
---------

Stacking the :math:`n` units gives

.. math::

	\left[
	\begin{array}{c}
	y_{1t} \\
	y_{2t} \\
	\vdots  \\
	y_{nt}%
	\end{array}%
	\right] =C\left( r_{t}\right) \left[
	\begin{array}{c}
	x_{1t} \\
	x_{2t} \\
	\vdots  \\
	x_{nt}%
	\end{array}%
	\right] +B_{1}\left( r_{t}\right) \left[
	\begin{array}{c}
	y_{1t-1} \\
	y_{2t-1} \\
	\vdots  \\
	y_{nt-1}%
	\end{array}%
	\right] +...+B_{p}\left( r_{t}\right) \left[
	\begin{array}{c}
	y_{1t-p} \\
	y_{2t-p} \\
	\vdots  \\
	y_{nt-p}%
	\end{array}%
	\right] +u_{t}

with :math:`r_{t}=1,2,...,h` and transition probabilities
:math:`p_{r_{t},r_{t+1}}\left( I_{t}\right)`. The blocks :math:`B_{1},...,B_{p}`
(dynamic / lag coefficients, named ``b1``, ..., ``bp`` -- ``b(row,col)``, with
the lag index omitted, refers to all lags) and :math:`C` (deterministic /
exogenous coefficients, named ``c``) carry, on and off the diagonal, both
within-unit and cross-unit dynamics; how much of this is shared across units is
governed by the homogeneity assumption:

- ``'pooled'`` -- all units share the same coefficients;
- ``'meanGroup'`` -- mean-group estimator (average across units);
- ``'static'`` -- the deterministic (constant / exogenous) coefficients are
  common, the dynamics are unit-specific;
- ``'dynamic'`` -- the lag coefficients are common, the constants are
  unit-specific;
- ``'independent'`` -- nothing in common (a separate VAR per unit).

Creating a panel VAR
--------------------

The first argument is a ``panel`` struct describing the cross-section; the rest
of the signature is the ``rfvar`` one (``exog``, ``nlags``, ``constant``,
``markov_chains`` are optional)::

	panel             = struct();
	panel.members     = {'US','CA','MX','BR'};
	panel.homogeneity = 'dynamic';

	endog = {'GROWTH','PAI','R'};

	mdl = prfvar(panel, endog, {}, 4, true);

You declare the variables once (``endog``) and the units once
(``panel.members``); internally RISE expands the variable list by appending the
unit names -- ``GROWTH_US``, ``GROWTH_CA``, ..., ``PAI_US``, ... -- so the
database of :doc:`time series <../DataManagement/Data Management>` you pass to
``estimate`` should carry those per-unit series (RISE's panel data handling
takes care of the stacking; ``translate_panel_output`` gives the results back
unit by unit). The list of units and the homogeneity of an existing object are
available through ``members`` and ``homogeneity``.

Estimation, identification, IRFs, decompositions, forecasting
-------------------------------------------------------------

These are called exactly as for a reduced-form VAR -- ``estimate`` (with an
optional prior built from ``prfvar.prior_template()`` and any linear
restrictions on the ``b``/``c`` coefficients), ``identification`` (and then
``structural_shocks`` / ``irf`` with the resulting ``Rfunc``),
``variance_decomposition``, ``historical_decomposition``, ``forecast``,
``bootstrap``. Restrictions are written on the *expanded* parameter names
(``b1(GROWTH_US, R_CA)=0`` for a cross-unit exclusion, etc.), but the
homogeneity assumption already imposes the bulk of the cross-unit structure.
See the reduced-form VAR chapter for the call patterns and the plotting helpers
(``quick_irfs``, ``plot_fanchart``, ``plot_decomp``, ...).

Adding regime switching
-----------------------

As for the reduced-form VAR, pass a Markov-chain structure as the last argument
and list the parameters it controls (on the expanded names); time-varying
transition probabilities are specified exactly as in the reduced-form VAR
chapter, and the switching parameters are given priors through
``prior.nonvar``.

.. todo::

   Add a full worked example (multi-country data, a couple of homogeneity
   assumptions compared, estimation, identified IRFs unit by unit via
   ``translate_panel_output``, and a regime-switching variant).

Technical documentation for prfvar objects
------------------------------------------

.. toctree::
   :maxdepth: 2
   :caption: Contents:

   prfvar_properties_methods